Mozahler

First of all, you don't need me to teach you how to set up your website. I've been doing this for a couple of days. There are many great, informative resources out there, and I've provided links to some of those I found particularly helpful. (check out Danijela's excellent overview: Create a Portfolio Website Using Publish˙

Every website created with Publish is a Swift package. When deployed, a pre-defined set of steps get executed that builds and renders the HTML components and styles them with CSS.

This is how John Sundell describes the core functionality of his Publish package.

It can be a bit confusing to work in so many languages at once: markdown, html, css, swift, not to mention the DSL's you have available to leverage stylistic and other changes across your projects. Publish, Ink, Splash are tools written to make the transition from markdown to html possible without you having to learn the ins and outs of web programming. Ultimately the idea is to express your intentions in Swift and to allow the publishing pipeline to transform the information into the correct html. It's a big ask. And it is doable.

Here's one way to get the ball rolling with your own website.

While the Publish package by John Sundell is an amazing accomplishment, there aren't a lot introductory tutorials that go beyond installing the standard boiler plate he provides out of the box. There are some well-written articles available for customizing pieces of your setup, and some highly recommended ones are linked below. On a separate entry I have documented part of my journey towards setting up this site.

One thing you need to do while working on putting your site together is to get to know what steps are involved, and what those steps actually do. Go ahead and peek into the Output folder after building and running your project. Is everything where you thought it would be placed? Are you puzzled by any of the content?

Take a look at this: Wrestling With Publish

This is an excellent collection of links to sites that have been customized along with a link to the GitHub repository for each the site. By going through the list your takeaway should be how varied the sites are set up. See if you can understand how they differ from each other. Because most of these have actual content included along with their source code you can actually find out how they made that happen.

Progressing to the Next Step

There are many ways to improve your site once you have gotten under way. Perhaps you feel it is lacking something, but you can't quite put your finger on what it might be. You can get a feel for how others have extended the basic setup. You can take a look at their site, and if you see something that catches your eye, go to their GitHub project and figure out how it was done. If that seems a little advanced for you, then start by browsing any of the tutorials that explain how to customize a theme or add publishing steps to the pipeline.

How Do Others Do It?

Try clicking on one of the links where someone describes a particular enhancement they made and how they accomplished it. You are going to have to go through a similar process any time you come up with an idea that is not configured out of the box. Just surfing through a site might give you some ideas on how to spruce up your own site. ˙

main.swift

main.swift is a file which contains a configuration information for your website. In this file you can add sections, specific item metadata, website properties, and configure publishing steps. Of course you can add other files, extend other protocols or processes in ways that better serve your specific needs. In order to do this well, however, it helps if you understand the underlying structure - including how things get done.

Plugins

Plugins are great for extending the capabilities of your site. They can be a little difficult to work with, however.
Adding a plugin to the Package.swift file isn't difficult, but there are some "gotchas" that you need to be aware of.
As time goes on it becomes easier to work with the SPM in Xcode. But there are still times when the compiler gets confused and you need to clean your build folder and exit the app.
Sometimes, miraculously, everything can start compiling again after performing this little dance.

Minimum Version

If you don't specify a miminum version of macOS in your package.swift file you may find it won't compile. The reason may seem a bit cryptic - the compiler tells you your target supports an old version of the OS, but you haven't mentioned one anywhere.

The solution isn't difficult: you need to add the platforms parameter to your initializer in Package.swift.
If you're using a pre-existing Package.swift file you may find it needs some updating.

There's a line at the top of Package.swift that tells the package manager which version of swift it can support.

// swift-tools-version:5.7

You'll find a this explanation on Apple's Developer Site:

The Swift tools version declares the version of the PackageDescription library, the minimum version of the Swift tools and Swift language compatibility version to process the manifest, and the required minimum version of the Swift tools to use the Swift package.

It's wise to update the tools version after an Xcode Upgrade, when possible. Similarly, if you start with an existing Package.swift file, the stated version may be out of date. This can result in Xcode not letting you specify the version of the OS you want -- It may not have existed when that version of tools was created.

Another reason for getting an unsupported version warning is when you have the wrong scheme selected. When you set up a new project from scratch it may default to iOS, for example. If you don't change it manually to macOS then it won't compile.

## Links

Wrestling With Publish

Danijela Vrzan